RISE's reporting system ======================== Description ---------------- RISE ships its own LaTeX-driven reporting system. The user-facing class is :ref:`rnotes `: a handle class that accumulates sections, text, figures, tables and equations, and renders them to PDF via ``pdflatex``. A legacy class :ref:`rprt ` is kept as a thin subclass of ``rnotes`` to preserve the historical positional constructor; new code should use ``rnotes`` directly. The system is PDF-only. PDF compilation requires a working LaTeX distribution on ``PATH`` (MiKTeX on Windows, TeX Live / MacTeX on Linux and macOS). ``rise_startup`` probes for ``pdflatex`` and warns if it is missing. Quick start ---------------- A minimal report: .. code-block:: matlab r = rnotes(title="My first report", author="Ola Normann"); r.section("Introduction") r.text("This is the body of the introduction.") publish(r, "report.pdf") ``r`` is a handle, so all subsequent ``r.section(...)``, ``r.figure(...)``, ``r.table(...)`` calls accumulate into the same report. ``publish`` is the final step and writes the ``.tex`` and ``.pdf`` next to the working directory. Multiple authors, with optional email and institution: .. code-block:: matlab authors = ["Alice Adams", "alice@example.org", "University of A"; "Bob Brown", "bob@example.org", "University of B"; "Carol Clarke", "", "University of C"]; r = rnotes(title="Switching DSGE: Policy or Volatility?", author=authors); The author argument accepts a string scalar (one author, name only), a column string vector (multiple authors, names only), or an ``N x {1,2,3}`` string array where the extra columns are email and/or institution. Email is detected automatically by the presence of ``@``. Structuring the document ------------------------- Sectioning commands mirror LaTeX: .. code-block:: matlab r.chapter("A chapter") % only with DocumentClass="report" or "book" r.section("A section") r.subsection("A subsection") r.subsubsection("A subsubsection") r.paragraph("A paragraph heading") r.subparagraph("A sub-paragraph heading") Each can be made un-numbered: .. code-block:: matlab r.section("Acknowledgements", Numbered=false) Sectioning commands register an internal label automatically; you can also pass an explicit one for cross-referencing: .. code-block:: matlab r.section("Methods", Label="sec:methods") A table of contents is requested at publish time: .. code-block:: matlab publish(r, "report.pdf", TOC=true) Adding content --------------- Text, lists and quotes: .. code-block:: matlab r.text("This paper studies the effect of policy on output.") r.itemize({"First point", "Second point", "Third point"}) r.enumerate({"Step one", "Step two", "Step three"}) r.description({ "DSGE", "Dynamic Stochastic General Equilibrium" "RBC", "Real Business Cycle" }) r.quote("A pithy quotation.") r.verbatim({"function y = f(x)", " y = x.^2;", "end"}) r.footnote("This is a footnote attached to the previous paragraph.") r.url("https://www.example.org") Equations are added by passing a LaTeX expression. The class auto-wraps plain expressions in an ``equation`` environment; if the expression already contains an environment (``\begin{align}``, ``\begin{gather}``, etc.) it is left untouched. .. code-block:: matlab r.equation("y_t = \rho y_{t-1} + \varepsilon_t") r.equation("E_{t} \pi_{t+1} = \beta \pi_t + \kappa x_t", ... Numbered=false, Label="eq:nkp") Figures can be added from an existing handle: .. code-block:: matlab fh = figure; x = 1:100; plot(x, log(x), "linewidth", 2); r.figure(fh, Caption="Log of x for x = 1..100") close(fh) Or from a file on disk: .. code-block:: matlab r.figure("path/to/saved.png", Caption="An imported figure") For multi-panel figures, ``create_figure`` builds the figure from a specification of subplots: .. code-block:: matlab subplots = { {ts("2000Q1", cumsum(randn(60,1))), "caption", "Series A"} {ts("2000Q1", cumsum(randn(60,1))), "caption", "Series B", ... "highlighted_dates", {date2serial({"2008Q4","2009Q4"})}} }; r.create_figure(subplots, Caption="Two random walks") Tables accept numeric arrays, cell arrays, or MATLAB ``table`` objects: .. code-block:: matlab data = randn(4, 3); headers = ["A", "B", "C"]; rows = ["Row 1"; "Row 2"; "Row 3"; "Row 4"]; r.table(data, ... Headers = headers, ... RowNames = rows, ... Caption = "Sample table", ... Precision = 3) For tables with more than ``MaxRows`` rows (default 10) ``table`` emits a ``longtable`` so the table breaks across pages naturally. Conditional formatting applies a colour or weight to cells passing a test: .. code-block:: matlab fmt = struct("test", @(x) x > 0.5, "action", {"red","bold"}); r.table(data, Headers=headers, FormatFuncs=fmt) Page control ------------- The page-control primitives mirror LaTeX: .. code-block:: matlab r.newpage() % \\newpage - force a new page now r.pagebreak() % \\pagebreak - suggest a break here r.clearpage() % \\clearpage - flush pending floats r.cleardoublepage() % \\cleardoublepage - next page is odd-numbered Publishing ----------- ``publish`` compiles the accumulated body to PDF. The first argument after ``obj`` is the savefile name; it must be a filename only, with no path component. All formatting choices live on ``publish`` as name-value arguments: .. code-block:: matlab publish(r, "report.pdf", ... DocumentClass = "report", ... PaperSize = "a4paper", ... PointSize = "11pt", ... Orientation = "landscape", ... TOC = true, ... NumPasses = 2) ``DocumentClass`` accepts ``article``, ``report``, ``book``, ``letter``, ``proc`` and ``minimal``. ``NumPasses`` controls the number of ``pdflatex`` runs, which determines whether cross-references and the TOC resolve on the same compile (default ``2``). ``Packages`` and ``PreambleAdditions`` are escape hatches for advanced uses; the default preamble already loads ``graphicx``, ``amsmath``, ``amssymb``, ``hyperref``, ``xcolor``, ``longtable``, ``booktabs``, ``listings`` and others. .. _rprt: Legacy ``@rprt`` compatibility ------------------------------- ``rprt`` is a thin subclass of ``rnotes`` that keeps the historical positional constructor working: .. code-block:: matlab xrep = rprt("Title", "Ola Normann", "orientation", "landscape"); The legacy author shapes (struct array with ``Name`` / ``Email`` / ``Institution`` fields, cell of structs) and the legacy parameter names on individual methods (``numbering``, ``format_funcs``, ``maxRows``, ``precision``, and the ``term`` / ``description`` struct form on ``description``) are translated to their ``rnotes`` equivalents internally. The legacy method names ``plain``, ``rise_file`` and ``rise_model_parameterization`` forward to ``text``, ``dsge`` and ``addParameterTable`` respectively. New code should not use ``rprt`` — the subclass exists only so that existing example scripts and external user code keep working without modification. Details ------------- .. toctree:: :maxdepth: 2 :caption: Contents: rnotes_reporting